.TH E1432_WRITE_SRCBUFFER_DATA 3 E1432
.SH NAME
.nf
e1432_write_srcbuffer_data \- Write arbitrary data to source
e1432_check_src_arbrdy \- Check data buffer full/empty status
e1432_get_src_arbstates \- Get data buffer full/empty status
.fi
.IX e1432_write_srcbuffer_data(3) 3
.IX e1432_check_src_arbrdy(3) 3
.IX e1432_get_src_arbstates(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_write_srcbuffer_data(E1432ID hw, SHORTSIZ16 chanID,
                                      LONGSIZ32 *dataPtr,
                                      LONGSIZ32 numwords,
                                      SHORTSIZ16 mode)

SHORTSIZ16 e1432_check_src_arbrdy(E1432ID hw, SHORTSIZ16 chanID,
                                      SHORTSIZ16 mode);

SHORTSIZ16 e1432_get_src_arbstates(E1432ID hw, SHORTSIZ16  chanID,
        LONGSIZ32 *xfrbuf_wds, LONGSIZ32 *srcbuf_state_AB,
        LONGSIZ32 *srcbuf_state_A, LONGSIZ32 *srcbuf_state_B)
.cE
.SH DESCRIPTION
\fIe1432_write_srcbuffer_data\fR transfers arbitrary data from the
host to the module's transfer buffer where it is then transferred to
the source board in the module.  The source buffer internally consists
of two buffers which alternate in continuous mode.  Returns 0 if
successful or a (negative) error number if an error.

NOTE: Under some circumstances, the data pointed to by \fIdataPtr\fR
may be byte swapped after the call to
\fIe1432_write_srcbuffer_data\fR.  This may pose a problem for the
application if it reuses that data.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIchanID\fR is a channel ID.  Group IDs are not yet supported.

\fIdataPtr\fR points to the data to be transferred.  Only the most
significant 24 bits of this data are used, the bottom eight bits are
completely ignored.

The data format must be 32bit signed fraction (2's complement),
normalized to full scale.  The maximum value is (2^31)-1 = 2147483647
= 0x7FFFFFFF = 32 bit fractional .999999999.  The minimum value is
-(2^31) = -2147483648 = 0x80000000 = 32 bit fractional -1.

.ne 20
Once normalized so that full scale equals 1, floating-point data can
be converted as follows:

.cS
    /* Floats typically have only 23 bits of mantissa, while doubles
       typically have 53 bits.  So use double to ensure that we
       preserve all 24 bits that the source will use. */

    double data[DATALENGTH];  /* normalized data */
    long arbdata[DATALENGTH]; /* data to be transferred */
    double x;

    for (i = 0; i < DATALENGTH; i++)
    {
        x = data[i];
        if (x > 8388607.0 / 8388608.0)
            x = 8388607.0 / 8388608.0;
        else if (x < -1.0)
            x = -1.0;
        arbdata[i] = floor(8388608.0 * x + 0.5) << 8;
    }
.cE

For a data value of 1, the output voltage is =
\fIe1432_set_range\fR * \fIe1432_set_amp_scale\fR.

\fInumwords\fR is the size of this data array.  Normally this must be
less than or equal to \fBE1432_SRC_DATA_NUMWORDS_MAX\fR, which is
4096.

If all of these are true:
.IP "1." 5
The module has no active inputs
.IP "2." 5
The module has DRAM
.IP "3." 5
The source channel is in source mode \fBE1432_SOURCE_MODE_ARB\fR
.PP
then \fInumwords\fR is not limited to
\fBE1432_SRC_DATA_NUMWORDS_MAX\fR, and can be as large as the source
data buffer size.  For more information on the use of DRAM for source
buffers, see the manual page for \fIe1432_set_srcbuffer_mode\fR.

\fImode\fR determines the transfer mode and may have the following values:

In \fBE1432_SRC_DATA_MODE_WAITA\fR, \fBE1432_SRC_DATA_MODE_WAITB\fR,
and \fBE1432_SRC_DATA_MODE_WAITAB\fR modes,
\fIe1432_write_srcbuffer_data\fR does not return until the data is
both transferred to the module's transfer buffer and from there to
the source buffer (A, B, or A concatenated with B), if possible.

In \fBE1432_SRC_DATA_MODE_A\fR, \fBE1432_SRC_DATA_MODE_B\fR, and
\fBE1432_SRC_DATA_MODE_AB\fR modes, \fIe1432_write_srcbuffer_data\fR
returns as soon as data is transferred to the module's transfer
buffer.  Transfer to the source board occurs in the background.
\fBE1432_SRC_DATA_MODE_AB\fR must be used for e1432_set_srcbuffer_mode
set to \fBE1432_SRCBUFFER_CONTINUOUS\fR.

\fIe1432_check_src_arbrdy\fR should be used to determine when more
data may be transferred.

\fIe1432_check_src_arbrdy\fR queries whether the module's transfer
buffer is ready to accept more data.  The returned value is set to 1
if more data may be transferred and 0 if there is no room currently
available for more data to be transferred.  If an error, it returns a
(negative) error number.

\fIe1432_get_src_arbstates\fR can be used to determine which buffers
data may be transferred to, for special case buffer management.
Generally this is not needed, as \fIe1432_check_src_arbrdy\fR is an
easier way to determine if the source is ready for more data.  This
returns 0 if successful or a (negative) error number if not.

\fIxfrbuf_wds\fR points to the number of words remaining in the transfer
buffer.  \fI*xfrbuf_wds\fR will be zero for a successfully completed data
transfer.

\fIsrcbuf_state_A\fR points to the state of the A buffer.

\fIsrcbuf_state_B\fR points to the state of the B buffer.

\fIsrcbuf_state_AB\fR points to the state of the buffer of A
concatenated with B.  If buffers A and B are in the same state, then
that is the state of AB.  If buffers and and B are in different
states, then the state of AB is reported as \fBE1432_SRCBUF_RDY\fR.

These buffer states can have the following values:

\fBE1432_SRCBUF_AVAIL\fR, the buffer is ready to be started to accept data.
This is the state immediately after using
\fIe1432_set_srcbuffer_init\fR.

\fBE1432_SRCBUF_RDY\fR, the buffer is ready to continue to accept
data.  This is the state after sending at least some data to the
source, but the source is not yet full.

\fBE1432_SRCBUF_FULL\fR, the buffer is full and not ready to accept
data.  When the srcbuffer mode is set to
\fBE1432_SRCBUFFER_PERIODIC_A\fR, then the B buffer is not used, so
the status of the B buffer will be \fBE1432_SRCBUF_FULL\fR.

The source must be set to \fBE1432_SOURCE_MODE_ARB\fR mode or
\fBE1432_SOURCE_MODE_BARB\fR using \fIe1432_set_source_mode\fR in
order for these functions to operate properly.

.SH "RESET VALUE"
Not applicable.
.SH "RETURN VALUE"
\fIe1432_write_srcbuffer_data\fR and \fIe1432_get_src_arbstates\fR
return 0 if successful, or a (negative) error number otherwise.

\fIe1432_check_src_arbrdy\fR returns 1 if more data may be transferred, a 0
if there is no room currently available for more data to be transferred, or
a (negative) error number.

.SH "SEE ALSO"
.na
e1432_set_range, e1432_set_amp_scale, e1432_set_srcbuffer_init,
e1432_set_srcbuffer_mode, e1432_set_srcbuffer_size
.ad
